/**
 * Copyright 2009 Sergio Bossa
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */
package com.googlecode.actorom;

/**
 * The topology is used to create {@link Actor} instances and keep track of them into a message-based system.
 * <br><br>
 * Actorom provides two different topology implementations:
 * <ul>
 * <li><strong>Local</strong> topology, providing a local-only, in-memory, in-vm, implementation
 * (see {@link com.googlecode.actorom.local.LocalTopology}).</li>
 * <li><strong>Client/Server</strong> topology, providing an in-memory implementation with remoting capabilities based on TCP sockets,
 * in order to let clients connect and remotely spawn/access actors
 * (see {@link com.googlecode.actorom.remote.ClientTopology} and {@link com.googlecode.actorom.remote.ServerTopology}).</li>
 * </ul>
 *
 * @author Sergio Bossa
 */
public interface Topology {

    /**
     * Create a new {@link Actor} and get its {@link Address}.<br>
     * A spawned actor is active and ready to handle sent messages until it fails or is killed
     * by a {@link KillActorException}.
     * <br><br>
     * The string identifier is used to properly build the complete {@link Address},
     * and must be unique inside this topology.
     * <br><br>
     * The handler object is used to define the {@link Actor} behaviour by properly applying
     * annotations contained into the <code>com.googlecode.actorom.annotation</code> package.
     *
     * @param id The actor unique identifier.
     * @param handler The actor handler.
     * @return The actor {@link Address}.
     */
    public Address spawnActor(String id, Object handler);

    /**
     * Create and return a new {@link Actor}.<br>
     * A spawned actor is active and ready to handle sent messages until it fails or is killed
     * by a {@link KillActorException}.
     * <br><br>
     * The string identifier is used to properly build the complete {@link Address},
     * and must be unique inside this topology.
     * <br><br>
     * The handler object is used to define the {@link Actor} behaviour by properly applying
     * annotations contained into the <code>com.googlecode.actorom.annotation</code> package.
     *
     * @param id The actor unique identifier.
     * @param handler The actor handler.
     * @return The created {@link Actor}.
     */
    public Actor spawnAndGetActor(String id, Object handler);

    /**
     * Get the {@link Actor} corresponding to the given {@link Address}.<br>
     * The returned actor (if not null) is guaranteed to be active at the moment of this method call.
     *
     * @param address The actor {@link Address}.
     * @return The actor, or null if no active actor is found.
     */
    public Actor getActor(Address address);

    /**
     * Shutdown this topology, disposing all resources currently held.
     */
    public void shutdown();
}
